Propagazione del Contesto Asincrono in JavaScript: Tracciamento delle Richieste e Continuazione con AsyncLocalStorage

Nello sviluppo moderno di JavaScript lato server, in particolare con Node.js, le operazioni asincrone sono onnipresenti. Gestire lo stato e il contesto attraverso questi confini asincroni può essere una sfida. Questo articolo esplora il concetto di propagazione del contesto asincrono, concentrandosi su come utilizzare AsyncLocalStorage per ottenere efficacemente il tracciamento delle richieste e la continuazione. Esamineremo i suoi vantaggi, limiti e applicazioni reali, fornendo esempi pratici per illustrarne l'utilizzo.

Comprendere la Propagazione del Contesto Asincrono

La propagazione del contesto asincrono si riferisce alla capacità di mantenere e propagare informazioni di contesto (ad es. ID di richiesta, dettagli di autenticazione utente, ID di correlazione) attraverso le operazioni asincrone. Senza una corretta propagazione del contesto, diventa difficile tracciare le richieste, correlare i log e diagnosticare problemi di performance nei sistemi distribuiti.

Gli approcci tradizionali alla gestione del contesto si basano spesso sul passaggio esplicito di oggetti di contesto attraverso le chiamate di funzione, il che può portare a codice verboso e soggetto a errori. AsyncLocalStorage offre una soluzione più elegante fornendo un modo per archiviare e recuperare i dati di contesto all'interno di un singolo contesto di esecuzione, anche attraverso operazioni asincrone.

Introduzione ad AsyncLocalStorage

AsyncLocalStorage è un modulo integrato di Node.js (disponibile dalla versione v14.5.0) che fornisce un modo per archiviare dati locali alla durata di un'operazione asincrona. In sostanza, crea uno spazio di archiviazione che viene preservato attraverso le chiamate await, le promise e altri confini asincroni. Ciò consente agli sviluppatori di accedere e modificare i dati di contesto senza doverli passare esplicitamente.

Caratteristiche principali di AsyncLocalStorage:

• Propagazione Automatica del Contesto: I valori memorizzati in AsyncLocalStorage vengono propagati automaticamente attraverso le operazioni asincrone all'interno dello stesso contesto di esecuzione.
• Codice Semplificato: Riduce la necessità di passare esplicitamente oggetti di contesto attraverso le chiamate di funzione.
• Osservabilità Migliorata: Facilita il tracciamento delle richieste e la correlazione di log e metriche.
• Thread-Safety: Fornisce un accesso thread-safe ai dati di contesto all'interno del contesto di esecuzione corrente.

Casi d'Uso per AsyncLocalStorage

AsyncLocalStorage è prezioso in vari scenari, tra cui:

• Tracciamento delle Richieste: Assegnare un ID univoco a ogni richiesta in arrivo e propagarlo durante tutto il ciclo di vita della richiesta a fini di tracciamento.
• Autenticazione e Autorizzazione: Memorizzare i dettagli di autenticazione dell'utente (ad es. ID utente, ruoli, permessi) per l'accesso a risorse protette.
• Logging e Auditing: Aggiungere metadati specifici della richiesta ai messaggi di log per un migliore debugging e auditing.
• Monitoraggio delle Performance: Tracciare il tempo di esecuzione di diversi componenti all'interno di una richiesta per l'analisi delle performance.
• Gestione delle Transazioni: Gestire lo stato transazionale attraverso più operazioni asincrone (ad es. transazioni di database).

Esempio Pratico: Tracciamento delle Richieste con AsyncLocalStorage

Illustriamo come utilizzare AsyncLocalStorage per il tracciamento delle richieste in una semplice applicazione Node.js. Creeremo un middleware che assegna un ID univoco a ogni richiesta in arrivo e lo rende disponibile durante tutto il ciclo di vita della richiesta.

Esempio di Codice

Innanzitutto, installa i pacchetti necessari (se richiesto):

            npm install uuid express
            

              
                Copy
              
            
          

Ecco il codice:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware per assegnare un ID di richiesta e memorizzarlo in AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simula un'operazione asincrona
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Gestore della rotta
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

In questo esempio:

1. Creiamo un'istanza di AsyncLocalStorage.
2. Definiamo un middleware che assegna un ID univoco a ogni richiesta in arrivo utilizzando la libreria uuid.
3. Utilizziamo asyncLocalStorage.run() per eseguire il gestore della richiesta all'interno del contesto di AsyncLocalStorage. Questo assicura che qualsiasi valore memorizzato in AsyncLocalStorage sia disponibile durante tutto il ciclo di vita della richiesta.
4. All'interno del middleware, memorizziamo l'ID della richiesta in AsyncLocalStorage usando asyncLocalStorage.getStore().set('requestId', requestId).
5. Definiamo una funzione asincrona doSomethingAsync() che simula un'operazione asincrona e recupera l'ID della richiesta da AsyncLocalStorage.
6. Nel gestore della rotta, recuperiamo l'ID della richiesta da AsyncLocalStorage e lo includiamo nella risposta.

Quando esegui questa applicazione e invii una richiesta a http://localhost:3000, vedrai l'ID della richiesta registrato sia nel gestore della rotta che nella funzione asincrona, dimostrando che il contesto viene propagato correttamente.

Spiegazione

• Istanza di AsyncLocalStorage: Creiamo un'istanza di AsyncLocalStorage che conterrà i nostri dati di contesto.
• Middleware: Il middleware intercetta ogni richiesta in arrivo. Genera un UUID e poi utilizza asyncLocalStorage.run per eseguire il resto della pipeline di gestione della richiesta *all'interno* del contesto di questa archiviazione. Questo è fondamentale; assicura che qualsiasi cosa a valle abbia accesso ai dati memorizzati.
• asyncLocalStorage.run(new Map(), ...): Questo metodo accetta due argomenti: una nuova Map vuota (puoi usare altre strutture dati se appropriate per il tuo contesto) e una funzione di callback. La funzione di callback contiene il codice che deve essere eseguito all'interno del contesto asincrono. Qualsiasi operazione asincrona avviata all'interno di questa callback erediterà automaticamente i dati memorizzati nella Map.
• asyncLocalStorage.getStore(): Restituisce la Map che è stata passata a asyncLocalStorage.run. Lo usiamo per memorizzare e recuperare l'ID della richiesta. Se run non è stato chiamato, questo restituirà undefined, motivo per cui è importante chiamare run all'interno del middleware.
• Funzione Asincrona: La funzione doSomethingAsync simula un'operazione asincrona. Fondamentalmente, anche se è asincrona (usando setTimeout), ha ancora accesso all'ID della richiesta perché è in esecuzione all'interno del contesto stabilito da asyncLocalStorage.run.

Utilizzo Avanzato: Combinazione con Librerie di Logging

L'integrazione di AsyncLocalStorage con librerie di logging (come Winston o Pino) può migliorare significativamente l'osservabilità delle tue applicazioni. Iniettando dati di contesto (ad es. ID richiesta, ID utente) nei messaggi di log, puoi facilmente correlare i log e tracciare le richieste attraverso diversi componenti.

Esempio con Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modified)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Registra la richiesta in arrivo
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

In questo esempio:

• Creiamo un'istanza del logger Winston e la configuriamo per includere l'ID della richiesta da AsyncLocalStorage in ogni messaggio di log. La parte chiave è winston.format.printf, che recupera l'ID della richiesta (se disponibile) da AsyncLocalStorage. Controlliamo se asyncLocalStorage.getStore() esiste per evitare errori durante il logging al di fuori di un contesto di richiesta.
• Aggiorniamo il middleware per registrare l'URL della richiesta in arrivo.
• Aggiorniamo il gestore della rotta e la funzione asincrona per registrare i messaggi utilizzando il logger configurato.

Ora, tutti i messaggi di log includeranno l'ID della richiesta, rendendo più facile tracciare le richieste e correlare i log.

Approcci Alternativi: cls-hooked e Async Hooks

Prima che AsyncLocalStorage fosse disponibile, librerie come cls-hooked erano comunemente utilizzate per la propagazione del contesto asincrono. cls-hooked utilizza gli Async Hooks (un'API di Node.js a più basso livello) per ottenere funzionalità simili. Sebbene cls-hooked sia ancora ampiamente utilizzato, AsyncLocalStorage è generalmente preferito per la sua natura integrata e le prestazioni migliorate.

Async Hooks (async_hooks)

Gli Async Hooks forniscono un'API a più basso livello per tracciare il ciclo di vita delle operazioni asincrone. Sebbene AsyncLocalStorage sia costruito sopra gli Async Hooks, usarli direttamente è spesso più complesso e meno performante. Gli Async Hooks sono più appropriati per casi d'uso molto specifici e avanzati in cui è richiesto un controllo granulare sul ciclo di vita asincrono. Evita di usare gli Async Hooks direttamente a meno che non sia assolutamente necessario.

Perché preferire AsyncLocalStorage a cls-hooked?

• Integrato: AsyncLocalStorage è parte del core di Node.js, eliminando la necessità di dipendenze esterne.
• Performance: AsyncLocalStorage è generalmente più performante di cls-hooked grazie alla sua implementazione ottimizzata.
• Manutenzione: Essendo un modulo integrato, AsyncLocalStorage è mantenuto attivamente dal team core di Node.js.

Considerazioni e Limitazioni

Sebbene AsyncLocalStorage sia uno strumento potente, è importante essere consapevoli dei suoi limiti:

• Confini del Contesto: AsyncLocalStorage propaga il contesto solo all'interno dello stesso contesto di esecuzione. Se si passano dati tra processi o server diversi (ad es. tramite code di messaggi o gRPC), sarà comunque necessario serializzare e deserializzare esplicitamente i dati di contesto.
• Memory Leak: Un uso improprio di AsyncLocalStorage può potenzialmente portare a perdite di memoria se i dati di contesto non vengono ripuliti correttamente. Assicurati di utilizzare asyncLocalStorage.run() correttamente ed evita di archiviare grandi quantità di dati in AsyncLocalStorage.
• Complessità: Sebbene AsyncLocalStorage semplifichi la propagazione del contesto, può anche aggiungere complessità al codice se non usato con attenzione. Assicurati che il tuo team capisca come funziona e segua le best practice.
• Non un Sostituto delle Variabili Globali: AsyncLocalStorage *non* è un sostituto delle variabili globali. È specificamente progettato per propagare il contesto all'interno di una singola richiesta o transazione. Un uso eccessivo può portare a codice strettamente accoppiato e rendere i test più difficili.

Best Practice per l'Uso di AsyncLocalStorage

Per utilizzare efficacemente AsyncLocalStorage, considera le seguenti best practice:

• Usa Middleware: Usa un middleware per inizializzare AsyncLocalStorage e archiviare i dati di contesto all'inizio di ogni richiesta.
• Archivia Dati Minimi: Archivia solo i dati di contesto essenziali in AsyncLocalStorage per minimizzare l'overhead di memoria. Evita di archiviare oggetti di grandi dimensioni o informazioni sensibili.
• Evita l'Accesso Diretto: Incapsula l'accesso a AsyncLocalStorage dietro API ben definite per evitare un accoppiamento stretto e migliorare la manutenibilità del codice. Crea funzioni di supporto o classi per gestire i dati di contesto.
• Considera la Gestione degli Errori: Implementa la gestione degli errori per gestire con garbo i casi in cui AsyncLocalStorage non è inizializzato correttamente.
• Testa a Fondo: Scrivi test unitari e di integrazione per assicurarti che la propagazione del contesto funzioni come previsto.
• Documenta l'Uso: Documenta chiaramente come AsyncLocalStorage viene utilizzato nella tua applicazione per aiutare gli altri sviluppatori a comprendere il meccanismo di propagazione del contesto.

Integrazione con OpenTelemetry

OpenTelemetry è un framework di osservabilità open-source che fornisce API, SDK e strumenti per la raccolta e l'esportazione di dati di telemetria (ad es. tracce, metriche, log). AsyncLocalStorage può essere integrato senza problemi con OpenTelemetry per propagare automaticamente il contesto di traccia attraverso le operazioni asincrone.

OpenTelemetry si basa pesantemente sulla propagazione del contesto per correlare le tracce tra diversi servizi. Utilizzando AsyncLocalStorage, puoi assicurarti che il contesto di traccia sia propagato correttamente all'interno della tua applicazione Node.js, consentendoti di costruire un sistema di tracciamento distribuito completo.

Molti SDK di OpenTelemetry utilizzano automaticamente AsyncLocalStorage (o cls-hooked se AsyncLocalStorage non è disponibile) per la propagazione del contesto. Controlla la documentazione dell'SDK OpenTelemetry che hai scelto per i dettagli specifici.

Conclusione

AsyncLocalStorage è uno strumento prezioso per la gestione della propagazione del contesto asincrono nelle applicazioni JavaScript lato server. Utilizzandolo per il tracciamento delle richieste, l'autenticazione, il logging e altri casi d'uso, puoi costruire applicazioni più robuste, osservabili e manutenibili. Sebbene esistano alternative come cls-hooked e gli Async Hooks, AsyncLocalStorage è generalmente la scelta preferita per la sua natura integrata, le prestazioni e la facilità d'uso. Ricorda di seguire le best practice e di essere consapevole dei suoi limiti per sfruttare efficacemente le sue capacità. La capacità di tracciare le richieste e correlare gli eventi attraverso le operazioni asincrone è cruciale per la costruzione di sistemi scalabili e affidabili, specialmente in architetture a microservizi e ambienti distribuiti complessi. L'uso di AsyncLocalStorage aiuta a raggiungere questo obiettivo, portando in definitiva a un migliore debugging, monitoraggio delle performance e salute generale dell'applicazione.